about Functions Advanced Methods |
您所在的位置:网站首页 › block-by-block method翻译 › about Functions Advanced Methods |
about_Functions_Advanced_Methods
Article
01/23/2023
5 minutes to read
Short description
Describes how functions that specify the CmdletBinding attribute can use the methods and properties that are available to compiled cmdlets. Long descriptionFunctions that specify the CmdletBinding attribute can access additional methods and properties through the $PSCmdlet variable. These methods include the following methods: Input-processing methods that compiled cmdlets use to do their work. The ShouldProcess and ShouldContinue methods that are used to get user feedback before an action is performed. The ThrowTerminatingError method for generating error records. Several Write methods that return different types of output.All the methods and properties of the PSCmdlet class are available to advanced functions. For more information, see System.Management.Automation.PSCmdlet. For more information about the CmdletBinding attribute, see about_Functions_CmdletBindingAttribute. For the CmdletBindingAttribute class, see System.Management.Automation.Cmdlet.CmdletBindingAttribute. Input processing methodsThe methods described in this section are referred to as the input processing methods. For functions, these three methods are represented by the begin, process, and end blocks of the function. You aren't required to use any of these blocks in your functions. Note These blocks are also available to functions that don't use the CmdletBinding attribute. The following example shows the outline of a function that contains a begin block for one-time preprocessing, a process block for multiple record processing, and an end block for one-time post-processing. Function Test-ScriptCmdlet { [CmdletBinding(SupportsShouldProcess=$True)] Param ($Parameter1) begin{} process{} end{} }Note Using either a begin or end block requires that you define all three blocks. When using any block, all PowerShell code must be inside one of the blocks. PowerShell 7.3 adds a clean block process method. beginThis block is used to provide optional one-time preprocessing for the function. The PowerShell runtime uses the code in this block once for each instance of the function in the pipeline. processThis block is used to provide record-by-record processing for the function. You can use a process block without defining the other blocks. The number of process block executions depends on how you use the function and what input the function receives. The automatic variable $_ or $PSItem contains the current object in the pipeline for use in the process block. The $input automatic variable contains an enumerator that's only available to functions and script blocks. For more information, see about_Automatic_Variables. Calling the function at the beginning, or outside of a pipeline, executes the process block once. Within a pipeline, the process block executes once for each input object that reaches the function. If the pipeline input that reaches the function is empty, the process block does not execute. The begin and end blocks still execute.Important If a function parameter is set to accept pipeline input, and a process block isn't defined, record-by-record processing will fail. In this case, your function will only execute once, regardless of the input. endThis block is used to provide optional one-time post-processing for the function. cleanThe clean block was added in PowerShell 7.3. The clean block is a convenient way for users to clean up resources that span across the begin, process, and end blocks. It's semantically similar to a finally block that covers all other named blocks of a script function or a script cmdlet. Resource cleanup is enforced for the following scenarios: when the pipeline execution finishes normally without terminating error when the pipeline execution is interrupted due to terminating error when the pipeline is halted by Select-Object -First when the pipeline is being stopped by Ctrl+c or StopProcessing()Caution Adding the clean block is a breaking change. Because clean is parsed as a keyword, it prevents users from directly calling a command named clean as the first statement in a script block. However, it's not likely to be a problem. The command can still be invoked using the call operator (& clean). Confirmation methods ShouldProcessThis method is called to request confirmation from the user before the function performs an action that would change the system. The function can continue based on the Boolean value returned by the method. This method can only be called only from within the Process{} block of the function. The CmdletBinding attribute must also declare that the function supports ShouldProcess (as shown in the previous example). For more information about this method, see System.Management.Automation.Cmdlet.ShouldProcess. For more information about how to request confirmation, see Requesting Confirmation. ShouldContinueThis method is called to request a second confirmation message. It should be called when the ShouldProcess method returns $true. For more information about this method, see System.Management.Automation.Cmdlet.ShouldContinue. Error methodsFunctions can call two different methods when errors occur. When a non-terminating error occurs, the function should call the WriteError method, which is described in the Write methods section. When a terminating error occurs and the function can't continue, it should call the ThrowTerminatingError method. You can also use the Throw statement for terminating errors and the Write-Error cmdlet for non-terminating errors. For more information, see System.Management.Automation.Cmdlet.ThrowTerminatingError. Write methodsA function can call the following methods to return different types of output. Notice that not all the output goes to the next command in the pipeline. You can also use the various Write cmdlets, such as Write-Error. WriteCommandDetailFor information about the WriteCommandDetails method, see System.Management.Automation.Cmdlet.WriteCommandDetail. WriteDebugTo provide information that can be used to troubleshoot a function, make the function call the WriteDebug method. The WriteDebug method displays debug messages to the user. For more information, see System.Management.Automation.Cmdlet.WriteDebug. WriteErrorFunctions should call this method when non-terminating errors occur and the function is designed to continue processing records. For more information, see System.Management.Automation.Cmdlet.WriteError. Note If a terminating error occurs, the function should call the ThrowTerminatingError method. WriteObjectThe WriteObject method allows the function to send an object to the next command in the pipeline. In most cases, WriteObject is the method to use when the function returns data. For more information, see System.Management.Automation.PSCmdlet.WriteObject. WriteProgressFor functions with actions that take a long time to complete, this method allows the function to call the WriteProgress method so that progress information is displayed. For example, you can display the percent completed. For more information, see System.Management.Automation.PSCmdlet.WriteProgress. WriteVerboseTo provide detailed information about what the function is doing, make the function call the WriteVerbose method to display verbose messages to the user. By default, verbose messages aren't displayed. For more information, see System.Management.Automation.PSCmdlet.WriteVerbose. WriteWarningTo provide information about conditions that may cause unexpected results, make the function call the WriteWarning method to display warning messages to the user. By default, warning messages are displayed. For more information, see System.Management.Automation.PSCmdlet.WriteWarning. Note You can also display warning messages by configuring the $WarningPreference variable or by using the Verbose and Debug command-line options. for more information about the $WarningPreference variable, see about_Preference_Variables. Other methods and propertiesFor information about the other methods and properties that can be accessed through the $PSCmdlet variable, see System.Management.Automation.PSCmdlet. For example, the ParameterSetName property allows you to see the parameter set that's being used. Parameter sets allow you to create a function that performs different tasks based on the parameters that are specified when the function is run. See also about_Automatic_Variables about_Functions about_Functions_Advanced about_Functions_Advanced_Parameters about_Functions_CmdletBindingAttribute about_Functions_OutputTypeAttribute about_Preference_Variables |
今日新闻 |
推荐新闻 |
CopyRight 2018-2019 办公设备维修网 版权所有 豫ICP备15022753号-3 |